home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / graphics / graphics3d / doc / graphics3d_e.doc next >
Text File  |  1999-05-25  |  57KB  |  1,840 lines
  1. TABLE OF CONTENTS
  2.  
  3. graphics3d.library/GD_switch_rp
  4. graphics3d.library/GD_clipbox
  5. graphics3d.library/GD_over
  6. graphics3d.library/GD_display3d
  7. graphics3d.library/GD_close_display3d
  8. graphics3d.library/GD_changeviewmode
  9. graphics3d.library/GD_changeviewmodeobj
  10. graphics3d.library/GD_touchpalette
  11. graphics3d.library/GD_moveforward
  12. graphics3d.library/GD_viewangle
  13. graphics3d.library/GD_frustum
  14. graphics3d.library/GD_createlightsource
  15. graphics3d.library/GD_ambientlight
  16. graphics3d.library/GD_positioncamera
  17. graphics3d.library/GD_aspectratio
  18. graphics3d.library/GD_clipmode
  19. graphics3d.library/GD_newobj
  20. graphics3d.library/GD_deleteobject
  21. graphics3d.library/GD_addobjvertex
  22. graphics3d.library/GD_addobjpoly
  23. graphics3d.library/GD_cattpoly
  24. graphics3d.library/GD_setobj
  25. graphics3d.library/GD_getobj
  26. graphics3d.library/GD_translateobject
  27. graphics3d.library/GD_positionobject
  28. graphics3d.library/GD_scaleobject
  29. graphics3d.library/GD_rotateobject
  30. graphics3d.library/GD_pickobj
  31. graphics3d.library/GD_paintframe
  32. graphics3d.library/GD_newview
  33. graphics3d.library/GD_recalcobj
  34. graphics3d.library/GD_cascene
  35. graphics3d.library/GD_int2fix
  36. graphics3d.library/GD_sfl2fix
  37. graphics3d.library/GD_dfl2fix
  38. graphics3d.library/GD_fix2int
  39. graphics3d.library/GD_fix2sfl
  40. graphics3d.library/GD_fix2dfl
  41. graphics3d.library/GD_loadobject
  42. graphics3d.library/GD_genpalette
  43. graphics3d.library/GD_modpoly
  44. graphics3d.library/GD_newtmap
  45. graphics3d.library/GD_rmtmap
  46. graphics3d.library/GD_newtmapf
  47. graphics3d.library/GD_colldetect
  48. graphics3d.library/GD_modobj
  49.  
  50. graphics3d.library/GD_display3d                graphics3d.library/GD_display3d
  51.    NAME
  52.     GD_display3d  --  To initialize all ambient for the library. 
  53.    SYNOPSIS
  54.     ambient3d=GD_display3d(win, x0, y0, scrw, scrh, vdist)
  55.                            A0   D0  D1  D2    D3    D4
  56.     struct ambient3d *GD_display3d(struct Window*,LONG,LONG,LONG,LONG,LONG);
  57.  
  58.    FUNCTION
  59.     create and initialized the ambient3d structure that is the describer          of the 3d scene and is used us input from all other functions.
  60.  
  61.    INPUTS
  62.     win   = pointer to Window structure of the window where you want
  63.         viewer the 3d scene.
  64.     x0,y0 = coordinates of upper left corner of the box that define
  65.         the visualizations limits of the scene.  
  66.     scrw  = width of this box it must be a multiply af 16 (max 3000).
  67.         It will use also as max X dimension of visualization box.
  68.     scrh  = height of this box (max. 3000).
  69.         It wilL use also as max Y dimension of visualization box.
  70.     vdist = distance from observer and proiection plane ,is expressed
  71.         as integer.
  72.    RESULT
  73.     ambient3d = pointer to ambient3d structure created, if it is equal 
  74.             to 0 than there is an error and the inizalization 
  75.             is aborted.
  76.  
  77.    BUGS
  78.     anyone note, if you find and tell me.
  79.  
  80.    NOTES
  81.     This function it must be use BEFORE all the other.
  82.     It can be used more than one time on the same program than storing 
  83.     separately the pointer returned, it possible to work simultaneously 
  84.     and independently an all the scenes so definited.
  85.     In the future perhaps I will make possible generate more scene of 
  86.     the same 3D space (for example to do more view) but all with the 
  87.     same memories areas for the objects definition .Now the library ever 
  88.     reallocate all areas and if the objects are much or complex it use 
  89.     very more memory. 
  90.  
  91.    SEE ALSO
  92.     GD_close_display3d
  93.  
  94. graphics3d.library/GD_close_display3d            graphics3d.library/GD_close_display3d
  95.    NAME
  96.     GD_close_display3d  --  erase all over the 3d scene viewing.
  97.  
  98.    SYNOPSIS
  99.     GD_close_display3d(in)
  100.                        A0
  101.     void GD_close_display3d(struct ambient3d *);
  102.  
  103.    FUNCTION
  104.     erase all that it was open and defined with GD_display3d included 
  105.     all objects of this scene.
  106.  
  107.    INPUTS
  108.     in = pointer to a ambient3d structure that you want delete.
  109.          If this pointer is 0 than it do nothing.
  110.  
  111.    RESULT
  112.  
  113.    BUGS
  114.     anyone note, if you find any tell me.
  115.  
  116.    NOTES
  117.     use it tipically at the end of the programm to erase all that is in 
  118.     relation with this library.
  119.  
  120.    SEE ALSO
  121.     GD_display3d
  122.  
  123. graphics3d.library/GD_changeviewmode            graphics3d.library/GD_changeviewmode
  124.    NAME
  125.     GD_changeviewmode  --  change the view mode of all objects
  126.  
  127.    SYNOPSIS
  128.     esi=GD_changeviewmode(in, modo, b_col)
  129.                           A0  D0    D1
  130.     LONG GD_changeviewmode(struct ambient3d *,LONG,LONG);
  131.  
  132.    FUNCTION
  133.     change simultaneously the view mode of ALL objects defined in the 
  134.     scene3d, for now is possible only this three view modes :
  135.     wire frame, solid shading and flat shading.
  136.  
  137.    INPUTS
  138.     in    = pointer to ambient3d structure of the 3d scene over there
  139.         you want work.
  140.         It must be greater than 0 otherwise the result is undefined.
  141.     modo  = new view mode : see GD_modobj().
  142.         b_col = color register n# to use for the border of polygon of 
  143.         objects.
  144.         If it is minor than 0 than no border.
  145.  
  146.    RESULT
  147.     esi = result , if different than 0 all ok, if equal to 0 than error
  148.           operation aborted.
  149.    BUGS
  150.     anyone note, if you find any tell me.
  151.  
  152.    NOTES
  153.  
  154.    SEE ALSO
  155.     GD_changeviewmodeobj
  156.  
  157. graphics3d.library/GD_changeviewmodeobj            graphics3d.library/GD_changeviewmodeobj
  158.     OBSOLETE -- use GD_modobj() instead
  159.  
  160.    NAME
  161.     GD_changeviewmodeobj  --  change the view mode of selected object
  162.  
  163.    SYNOPSIS
  164.     esi=GD_changeviewmodeobj(in, modo)
  165.                              A0  D0  
  166.     LONG GD_changeviewmodeobj(struct ambient3d *,LONG);
  167.  
  168.    FUNCTION
  169.     change the view mode of the actually selected object in the 3d scene
  170.     considered.
  171.  
  172.    INPUTS
  173.     in    = pointer to ambient3d structure of the 3d scene over there
  174.         you want work.
  175.         It must be greater than 0 otherwise the result is undefined.
  176.     modo  = new view mode :
  177.         0 -> wire frame              (use macro WIREF)
  178.             1 -> flat shading          (use macro FLAT)
  179.         2 -> solid shading          (use macro SOLID)
  180.         3 -> goraud shading          (use macro GORAUD)
  181.    RESULT
  182.     esi = result , if different than 0 all ok, if equal to 0 than error
  183.           operation aborted.
  184.    BUGS
  185.     really it wasn't tested now but I hope that it can work.
  186.  
  187.    NOTES
  188.  
  189.    SEE ALSO
  190.     GD_changeviewmode
  191.  
  192. graphics3d.library/GD_touchpalette            graphics3d.library/GD_touchpalette
  193.    NAME
  194.     GD_touchpalette  --  create a shaded color palette
  195.  
  196.    SYNOPSIS
  197.     GD_touchpalette(in, fr, lr, init_color, lastcolor)
  198.                     A0  D0  D1  A1          A2 
  199.     void GD_touchpalette(struct ambient3d *,LONG,LONG,struct rgbtype *,struct rgbtype *);
  200.  
  201.    FUNCTION
  202.     create a shaded color palette from two register color to use 
  203.     corrected the flat shading view mode.
  204.     
  205.    INPUTS
  206.     in         = pointer to ambient3d structure of the 3d scene over 
  207.              there you want work.
  208.              It must be greater than 0 otherwise the result is 
  209.              undefined.
  210.     fr         = first color register to set.
  211.         lr         = last color register to set.
  212.     init_color = pointer to rgbtype structure with initial RGB value 
  213.              of color.
  214.     lastcolor  = pointer to rgbtype structure with final RGB value 
  215.              of color.
  216.  
  217.    RESULT
  218.  
  219.    BUGS
  220.     anyone note, if you find any tell me.
  221.  
  222.    NOTES
  223.     the color assegned to the object will use us reference to 'fr' for 
  224.     the flat shading and it will be the darker shade , 'lr' the ligther 
  225.     shade.
  226.     It must be always used because the solid shading use the central 
  227.     shade us visualization color for polygons, using the object's color 
  228.     us reference to 'fr'. 
  229.     Now it have two range of value for RGB init_color and RGB lastcolor:
  230.     1- RGB component in the range from 0 to 15 then it can use machines
  231.        with ECS chipset and S.O < 3.0.
  232.     2- RGB component in the range from 0 to 255 than it MUST use machines
  233.        with almost AGA chipset and S.O. >= 3.0. 
  234.  
  235.    SEE ALSO
  236.  
  237. graphics3d.library/GD_moveforward            graphics3d.library/GD_moveforward
  238.    NAME
  239.     GD_moveforward  --  move the observer
  240.  
  241.    SYNOPSIS
  242.     GD_moveforward(in, dist)
  243.                    A0  D0
  244.     void GD_moveforward(struct ambient3d *,LONG);
  245.  
  246.    FUNCTION
  247.     move the observer of dist units forward to the point of view.
  248.  
  249.    INPUTS
  250.     in   = pointer to ambient3d structure of the 3d scene over there
  251.            you want work.
  252.            It must be greater than 0 otherwise the result is undefined.
  253.     dist = n# of units of observer displacement ,it can be negative 
  254.            (move backward) but it must be in FIX POINT that is:
  255.         integer value * 256 (or FIXV) +
  256.